package com.newmainsoftech.dao.entity.relation;

import java.util.Collection;

public interface HolderSide<E> extends IdentityAssurance {
	/**
	 * Getter of collection of holdee entities linked to this <code>{@link HolderSide}</code> entity.<br />
	 * The returned collection cannot be implementation instance of 
	 * <code>{@link BiLinkCollectionProxy}</code> (or its sub-class); rather an instance 
	 * of bare non-proxy collection type or collection proxy instance originally given by datastore 
	 * driver provider.
	 * 
	 * @return Collection of holdee entities linked to this <code>{@link HolderSide}</code> entity.
	 */
	Collection<E> getHoldees();
	
	/**
	 * Set collection of holdee entities purged out by <code>retainAll</code> operation (or 
	 * <code>removeAll</code> operation) on the collection instance returned by 
	 * <code>{@link #getHoldees()}</code> method.<br />
	 * The collection given via <code>purgedHoldees</code> argument will be useful for, when 
	 * <code>orphanRemoval</code> attribute has not set to true, persisting the holdee entities to update 
	 * to the removed state from collection (what represents relation with holder entity) by 
	 * <code>retainAll</code> operation.<br />
	 * (For the <code>removeAll</code> operation, the argument to the <code>removeAll</code> method will 
	 * be just handed as this <code>purgedHoldees</code> argument.) <br />
	 * 
	 * @param purgedHoldees Collection of holdee entities removed from the relation to holder by 
	 * <code>Collection.retainAll</code> operation or <code>Collection.removeAll</code> operation.<br />
	 * Either the underneath member field to store collection given by this argument or the implementation 
	 * of this method needs to be annotated with <code>&#x40;Transient</code> annotation when 
	 * <code>orphanRemoval</code> attribute has set to true, since those entities will be removed from 
	 * datastore.  
	 */
	void setPurgedHoldees( Collection<E> purgedHoldees);
}
